home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 7: Sunsite / Linux Cubed Series 7 - Sunsite Vol 1.iso / system / serial / zyxel-1.5 / zyxel-1 / usr / ZyXEL / README < prev    next >
Text File  |  1995-02-04  |  51KB  |  1,263 lines
  1.  
  2.  
  3.      #########       #       # ######### #
  4.         #        #      #  #           #
  5.           ##   #     #   #     #   #           #
  6.          #       #     #    ###    #######   #
  7.        ##       #     #   #     #   #           #
  8.       #       #     #  #      #  #           #
  9.      #########  ###### #       # ######### #########
  10.              #
  11.              #
  12.             #####
  13.  
  14.  
  15.     A control program for the ZyXEL U-1496 series MODEMs for use with the
  16.     Linux operating system (and other UNIX-like systems)
  17.  
  18.     This program manages the use of the ZyXEL MODEM for:
  19.  
  20.     - dial-in, for use by "uucp" and other programs started from
  21.       a login
  22.  
  23.     - dial-in security (checking username and password)
  24.  
  25.     - dial-back security
  26.  
  27.     - dial-out, e.g. using "cu", "uucp" or "seyon"
  28.  
  29.     - receiving FAXes
  30.  
  31.     - sending FAXes
  32.  
  33.     - polling for FAXes
  34.  
  35.     - handling incoming FAX polls
  36.  
  37.     - answering machine (voice mailbox)
  38.  
  39.     Everything is done in a single program, to keep things simple
  40.     and fast.  Multi-program solutions are available from others.
  41.     (e.g. modgetty, mgetty+sendfax)
  42.  
  43.     Copyright 1993-1995 by Rob Janssen, PE1CHL
  44.  
  45.     This program uses parts of "getty_ps", written by Paul Sutcliffe:
  46.     Copyright 1989,1990 by Paul Sutcliffe Jr.
  47.  
  48.     Permission is hereby granted to copy, reproduce, redistribute,
  49.     or otherwise use this software as long as: there is no monetary
  50.     profit gained specifically from the use or reproduction or this
  51.     software, it is not sold, rented, traded or otherwise marketed,
  52.     and this copyright notice is included prominently in any copy
  53.     made.
  54.  
  55.     The author make no claims as to the fitness or correctness of
  56.     this software for any use whatsoever, and it is provided as is.
  57.     Any use of this software is at the user's own risk.
  58.  
  59.  
  60. Info for those who upgrade from an earlier version
  61. --------------------------------------------------
  62.  
  63. This release has some major changes relative to 1.4
  64. When you have used 1.4 or earlier versions, please note the following:
  65.  
  66. - the extension of VOICE files has been changed from .zvd to .zad
  67.   this was done because the same change was made in ZFAX, ZyXEL's
  68.   DOS program for support of the modem.
  69.   rename any .zvd files you have in the "play", "record" and "archive"
  70.   directories (as well as anywhere else) from the .zvd to the .zad
  71.   extension for compatability with this release of ZyXEL.
  72.  
  73. - the programming of actions taken on DTMF input in the voice mailbox is
  74.   now more versatile.  both the single-key entries the user can make just
  75.   after entering a message, and the multi-key ("expert") entries are now
  76.   programmable.
  77.   when you have made changes to /usr/ZyXEL/commands (you should have, to
  78.   change the password) it is best to make the same changes in the newly
  79.   released version of this file, rather than attempting to update the
  80.   existing file.
  81.  
  82. - a text-to-speech synthesizer is now included.     it requires quite some
  83.   CPU power, though.  you may want to avoid using it when your machine
  84.   is less powerfull than a 486DX/33...    a machine without floating point
  85.   coprocessor will certainly not run it satisfactorily.
  86.   When your system is incapable of running the speech synthesizer, modify
  87.   the /usr/ZyXEL/keys and /usr/ZyXEL/commands files to use "play" commands
  88.   that play pre-recorded messages, or different kinds of "beep" commands
  89.   instead of all "say" commands in the files.  Examples are provided as
  90.   "keys.nosynth" and "commands.nosynth"
  91.   Also remove the SYNTH= line in /etc/default/ZyXEL.
  92.  
  93. - FAX transfer is now done in CLASS 2 mode (was ZFAX) by default.  this
  94.   means incoming FAXes can be processed by g3topbm and outgoing FAXes can
  95.   be generated by Ghostscript.
  96.   The old (ZFAX) method can still be selected at compiletime.
  97.  
  98.  
  99. Installation
  100. ------------
  101.  
  102. Installation should be most straightforward by unpacking everything from
  103. the distribution tar file:
  104.  
  105. cd /
  106. tar xvzf (path-to-your-tarfile)
  107.  
  108. This will install the program as /sbin/ZyXEL, and creates a defaults file
  109. in /etc/defaults/ZyXEL.
  110. Also a directory /usr/ZyXEL is created, which will hold the files used
  111. by the program.     Another location for this directory could be selected in
  112. the /etc/defaults/ZyXEL file.
  113.  
  114.  
  115. After loading the files the following setup files can be edited:
  116.  
  117. /etc/default/ZyXEL:
  118.  
  119. This file defines the behaviour of the program, and where it is to find
  120. the files it needs.  An example of such a file:
  121.  
  122. INIT="" AT&F&D3&S1&T4E0L6S2=255S13.1=1S40=120S42.6=1\r OK\r\n AT+FCLASS=8;+VIP;+FCLASS=0\r OK\r\n
  123. MUTE=M0
  124. READY=[1750,0,1]
  125. STATEFILE=/usr/ZyXEL/state.%s
  126. FIFO=/usr/ZyXEL/fifo.%s
  127. WFCLASS=8
  128. #DIALPREFIX=0w
  129. #LOCKPOLL=YES
  130. #MODEMPOLL=YES
  131. #DEBUG=170
  132. #
  133. # DATA mode stuff
  134. #
  135. VERSION=/etc/issue
  136. ISSUE=/etc/issue.modem
  137. TIMEOUT=60
  138. XOFF=NO
  139. LOGIN=/sbin/login
  140. LOGINENV=NO
  141. LOGINFLAGS=-p -f
  142. PROTECT=/etc/protect.usr
  143. #
  144. # FAX mode stuff
  145. #
  146. FAXID= +1234567890
  147. FAXDIR=/usr/ZyXEL/fax
  148. FAXFILE=%y%m%d-%H%M
  149. FAXMAIL=root
  150. FAXPOLL=/usr/ZyXEL/faxpoll/id%s
  151. FAXCOMP=0
  152. GHOSTSCRIPT=/usr/bin/gs
  153. GUNZIP=/bin/gunzip
  154. BUFFER=/usr/local/bin/buffer
  155. PSTEXT=/usr/local/bin/pstext
  156. #
  157. # VOICE mode stuff
  158. #
  159. PLAYDIR=/usr/ZyXEL/play
  160. RECDIR=/usr/ZyXEL/record
  161. RECFILE=%y%m%d-%H%M
  162. RECMODE=0
  163. SILENCE=25,70
  164. DROPMSG=5
  165. SHOWMSG=AA
  166. VOICECMD=/usr/ZyXEL/commands
  167. VOICEKEY=/usr/ZyXEL/keys
  168. ARCHIVE=/usr/ZyXEL/archive
  169. APIUSERLEVEL=7
  170. SYNTH=/usr/ZyXEL/zsynth
  171. SYNTHFLAGS=-R -d a
  172. #
  173. # PAGER stuff
  174. #
  175. #PAGERNUM=1234567
  176. #PAGERTYPE=31
  177. #
  178. # VOICE mode beeps
  179. # avoid freqs 440 Hz, 1200 Hz, 1300 Hz and 1800 Hz
  180. #
  181. #ANSWERTONE=[0,0,20][420,0,15]
  182. RECATTN=[933,0,4]
  183. RECDONE=[1866,0,1][0,0,1][1866,0,1]
  184. PROMPT1=[933,0,1]
  185. PROMPT2=[1866,0,1][933,0,1]
  186. ERROR=[500,0,3][0,0,1][500,0,3][0,0,5]
  187.  
  188.  
  189. Things you may want to change in this file:
  190.  
  191. On the first line, the INIT string is defined which is sent to the
  192. MODEM.    You may want to add a P just before the first \r if your
  193. telephone system does not allow the use of DTMF dialing.  (P = Pulse
  194. dialing)
  195. You may also want to insert or modify settings like S40=120 (enable
  196. distinctive ring detection) in the INIT string.     Leave the other
  197. initialization options as they are shown, at least until you fully
  198. understand their meaning and the implications of changing them.
  199.  
  200. The command after MUTE= is sent to the MODEM before answering calls in
  201. DATA or FAX mode.  You can use M0, M1, M2 or M3 to control the behaviour
  202. of the MODEM internal speaker.    Check the ZyXEL MODEM manual.
  203.  
  204. The tone after READY= is sent when ZyXEL has started and successfully
  205. initialized the MODEM.    It will sound a short beep from the internal
  206. speaker.  comment-out this line when you don't like that.
  207. (the 6.11a version that I am currently using beeps at a very low volume,
  208. making this feature mostly useless.  older versions sound a nice beep...)
  209.  
  210. STATEFILE and FIFO define locations of these files, and need no be
  211. changed when you keep /usr/ZyXEL as the home location of information for
  212. the program.
  213.  
  214. DIALPREFIX= can be used to define a fixed sequence to be sent before
  215. each number that is dialled from ZyXEL, e.g. to get an outside line when
  216. connected to a PABX.  When it is omitted, no prefix is sent.
  217.  
  218. When you use only clean programs like Taylor-UUCP and Seyon, you can
  219. omit the line LOCKPOLL=YES.  It causes the program to wake up every 15
  220. seconds to check for a lockfile, which is usually not necessary.  Use
  221. LOCKPOLL=YES only when you find that ZyXEL does not detect that certain
  222. programs have been using the port.
  223.  
  224. MODEMPOLL=YES causes the MODEM to be polled every 15 seconds to see if
  225. it is still 'alive'.  (AT is sent, and OK is expected back)
  226. You can omit this when you trust the MODEM not to silently die.
  227. (normally ZyXEL modems don't do that, but you can include this when you
  228. suspect your modem to be flaky)
  229.  
  230. The number after DEBUG= turns on some debugging output (will be written
  231. to the file /tmp/ZyXEL:line), it can be commented-out as soon as
  232. everything appears to be operating ok.    More debugging output can also
  233. be enabled, the number after DEBUG= is an octal number indicating
  234. classes of debug output:
  235.  
  236.     D_OPT        0001    /* option settings */
  237.     D_DEF        0002    /* defaults file processing */
  238.     D_UTMP        0004    /* utmp/wtmp processing */
  239.     D_CHAT        0010    /* MODEM chat (send/expect/waitfor) */
  240.     D_GETL        0040    /* get login name routine */
  241.     D_RUN        0100    /* other runtime diagnostics */
  242.     D_LOCK        0200    /* lockfile processing */
  243.  
  244. Note that debugging output is only available when the program has been
  245. compiled with debugging enabled.  This is controlled by an option in the
  246. makefile.  When the line: "DEBUG= -DDEBUG" is present in the makefile
  247. (without #-mark), the program will be compiled with debugging enabled.
  248.  
  249. DATA mode stuff:
  250.  
  251. VERSION and ISSUE determine the message sent to the user before the
  252. login: prompt appears.    ISSUE points to the file being printed in this
  253. case, and VERSION defines the file that can be referred to using @V in
  254. the ISSUE file.     As distributed, /etc/issue is assumed to contain the
  255. one-line text describing the system version, and the remainder of the
  256. info is added from /etc/issue.modem.
  257.  
  258. LOGIN= defines the program to be run when a valid username has been
  259. entered and callback checks have been made.
  260. LOGINFLAGS= defines the options passed to this program (before the
  261. username).  The "-p -f" options are valid for John F Haugh's shadow
  262. login package.    Your login may require different flags, or none at all.
  263. (-p means 'preserve environment variables' and -f indicates the user-id
  264. has already been validated by the calling program)
  265. When LOGINENV=YES, the environment variables defined by ZyXEL will be
  266. passed as extra arguments to LOGIN.  This can be used when the LOGIN
  267. program does not support the -p flag, and supports
  268. "login username var=value".
  269.  
  270.  
  271. FAX mode stuff:
  272.  
  273. Add your phone number after the FAXID=, it is used when answering FAX
  274. calls.    This string can be up to 25 characters.
  275.  
  276. FAXMAIL= defines a mail address where a notification message is sent
  277. whenever a FAX arrives.     When this definition is omitted, no message
  278. is sent.
  279.  
  280. FAXPOLL= defines the name of a file to be sent when an incoming FAX
  281. poll is detected.  A %s in this string will be replaced by the POLL-ID
  282. in the request, which is a 4-digit number.  When no POLL-ID is present,
  283. "0000" is used.
  284.  
  285. FAXCOMP= defines the FAX compression mode advertised to the remote FAX
  286. when answering.     Use FAXCOMP=0 when you want only 1-d coded FAXes to
  287. be received.  (g3topbm only supports this mode)
  288.  
  289. GHOSTSCRIPT= defines the pathname to the Ghostscript program, which is
  290. required when directly faxing text or Postscript files.
  291.  
  292. GUNZIP= defines the pathname to the Gunzip program, which is required
  293. when faxing gzipped Postscript files.
  294.  
  295. BUFFER= defines the pathname to a buffering program, which reads stdin,
  296. buffers some data and writes to stdout.     This is used between Ghostscript
  297. and the FAX sending routines, to enable Ghostscript to work ahead of the
  298. actual sending.     I use "buffer" by Lee McLoughlin, found on src.doc.ic.ac.uk.
  299.  
  300. PSTEXT= defines the pathname to a program that converts plain text on
  301. stdin to Postscript output on stdout.  It is required only to FAX plain
  302. text directly.
  303.  
  304. When you don't have one of the programs above, leave out the corresponding
  305. variable setting.  ZyXEL will not attempt to start the program in that case.
  306. This just means the corresponding file type cannot be directly FAXed.
  307.  
  308.  
  309. VOICE mode stuff:
  310.  
  311. RECMODE= defines the recording mode used for incoming messages.     known
  312. modes are:
  313.  
  314.     CELP        0    (only on PLUS models)
  315.     ADPCM2        1
  316.     ADPCM3        2
  317.     ADPCM4        3    (only with firmware 6.13 and newer)
  318.     ADPCM2+RESYNC    5    (only with firmware 6.10 and newer)
  319.     ADPCM3+RESYNC    6    (only with firmware 6.10 and newer)
  320.     ADPCM4+RESYNC    7    (only with firmware 6.13 and newer)
  321.     NEW ADPCM3        8    (only with firmware 6.13 and newer)
  322.     NEW ADPCM3+RESYNC  12    (only with firmware 6.13 and newer)
  323.  
  324. Selecting CELP on a non-PLUS modem will cause recording in ADPCM2 mode.
  325. Selecting a RESYNC mode on a modem with firmware before 6.10 will be
  326. ignored.  The corresponding mode without RESYNC will be used.  Selecting
  327. ADPCM4 with firmware before 6.13 will cause recording in ADPCM3 mode.
  328. Note that although recording is quite adaptive, playback isn't.  i.e.
  329. recordings made in any other mode than 1 or 2 are not playable on all
  330. available modems.
  331.  
  332. DROPMSG= defines a minimum recording time (in seconds) for an incoming
  333. voice message to be kept.  Messages shorter than this will be deleted
  334. immediately after the recording.  This is used to prevent recordings of
  335. only the BUSY tone being kept.    5 seconds seems to be a good value.
  336.  
  337. SHOWMSG=AA enables the "incoming messages available" indication on the
  338. "AA" LED on the MODEM.    Note that the "AA" LED is normally OFF, even
  339. when the program is in a mode where it will be answering the phone.
  340. This is because the decision to answer the phone is made based on the
  341. incoming RING indication, and the mode in which the program is at that
  342. time.
  343. When SHOWMSG=AA is in the file, the "AA" LED will be ON when a VOICE
  344. message is present in the voice messages recording directory.  This
  345. allows you to see at a glance whether a message is waiting, without
  346. having to check on the computer screen (which may be blanked or OFF).
  347.  
  348. APIUSERLEVEL= defines the userlevel that a user entering via the API
  349. FIFO will automatically get.  The API FIFO is the interface used by
  350. local programs, to let ZyXEL playback VOICE messages etc.  When the
  351. APIUSERLEVEL is suitably set, a local user can playback messages without
  352. first entering the password that would be required when doing this from
  353. the phone.
  354.  
  355. PAGER stuff:
  356.  
  357. PAGERNUM= defines the phone number to call to activate your pager.
  358.  
  359. PAGERTYPE= defines the method to use to call a pager.  different methods
  360. can be present in the program, and they are selected by a code.  the
  361. following methods are currently defined:
  362.  
  363.   31  Netherlands
  364.       Call the PAGERNUM number and wait until it answers (VOICE).
  365.       When numeric info is to be sent, wait for the end of the voice
  366.       announcement and the appearance of a DIAL tone, then send the info
  367.       using DTMF (even when local dialling is PULSE).  Info is
  368.       terminated with a # sign.
  369.       Then, wait for the confirmation voice message and beep.  Actually,
  370.       we cannot match that and wait for the BUSY signal which follows
  371.       immediately after the beep.
  372.       Note that the appearance of the second dialtone is dependent on
  373.       the kind of pager, and therefore it is your responsability to
  374.       configure the program (defaults file and keys/commands file) in
  375.       such a way that extra info is sent when the pager expects it, and
  376.       is not sent for a pager that does not support it.
  377.  
  378.  312  Alternative for Netherlands
  379.       Call a certain number in DATA mode (2400 baud, 7 bits, even
  380.       parity), and wait for the prompt for the pager number to call
  381.       ("=01=").  Send the PAGERNUM number followed by RETURN.  
  382.       Wait for prompt for numeric information ("=20=").  Send numeric
  383.       information, followed by RETURN.  Wait for confirmation ("=80=")
  384.       and disconnect.
  385.  
  386. When the above methods are not appropriate for your local situation,
  387. an extra code has to be added to the pager() function.  You could do that
  388. yourself (please send me the patches) or send a description of how your
  389. paging service works (similar to the descriptions above) and ask me to
  390. implement it.
  391.  
  392.  
  393. Other files that should be reviewed and edited:
  394.  
  395. /usr/ZyXEL/commands.example:
  396.  
  397. copy this file to /usr/ZyXEL/commands, and edit the numbers used as
  398. 'passwords' (123456 and 654321 in the example file) so that the
  399. passwords you use are not so easy to guess by others :-)
  400.  
  401.  
  402. /etc/inittab:
  403.  
  404. replace the line you may be currently using for the port (e.g. using
  405. getty or uugetty) with something like the following:
  406.  
  407.     s1:4:respawn:/sbin/ZyXEL ttyS1 57600
  408.  
  409. The baudrate "57600" may be too high when you use a '386 machine and
  410. have no 16550A UART installed.    You can decrease it to 38400 without
  411. much penalty.  Going down to 19200 or even 9600 will kill some of the
  412. voice mailbox capabilities...
  413.  
  414.  
  415. /etc/issue.modem:
  416.  
  417. The contents of this file are shown when a caller connects in DATA mode.
  418. The @letter sequence is used to insert system-dependent data.
  419. You can edit this file to direct callers towards public services
  420. available on your system (e.g. "bbs" and "nuucp")
  421.  
  422.  
  423. /etc/protect.usr:
  424.  
  425. This file defines the users that can login via the MODEM, and the
  426. password they have to use.  It can also define a telephone number to
  427. dial back to the calling user, for enhanced security.
  428. Because of this file, you can have restricted access via the modem,
  429. without having to set passwords on all your accounts.  Of course, you
  430. should only allow access to restricted applications (uucp, bbs) in that
  431. case, because a user getting a shell can simply "su" to any other user
  432. which does not have a password...
  433.  
  434. The layout of the /etc/protect.usr file is:
  435.  
  436. username:*
  437. username:password
  438. locationname:password:telephone_number
  439.  
  440. The first form allows access for users logging in as "username", without
  441. asking for a password.    The second form will cause a Password: prompt to
  442. appear, and the entered password will be checked.
  443. When the telephone_number is also present (third form), the line is
  444. disconnected and the specified number is then dialled.    When it answers,
  445. a connection is set up, and the user will be presented with the normal
  446. login: prompt of the operating system, so that he can login as any user
  447. whose password he knows.
  448.  
  449. Note that the passwords appear in plaintext, and have to be maintained
  450. by the system administrator using a text editor.  The file should
  451. therefore be owned by "root", and have mode 600 (-rw-------).
  452.  
  453.  
  454. /usr/ZyXEL/state.<linename>
  455.  
  456. This file (e.g. /usr/ZyXEL/state.ttyS1) defines the operating mode of
  457. the program for a certain line.     It consists of one to five lines with
  458. multiple space-separated tokens.  The following tokens are used:
  459.  
  460.     <mode> <number_of_rings> [<alt_number_of_rings>] [R<ringback_rings>]
  461.  
  462. The <mode> defines the mode in which calls are answered.  The following
  463. values are defined:
  464.  
  465.     DATA    answer in DATA/FAX mode, switch to VOICE when NO CARRIER
  466.     VOICE    answer in VOICE mode, switch to DATA/FAX after silence
  467.     FAX    answer only in FAX mode
  468.  
  469. The <number_of_rings> sets the moment at which the program answers the
  470. phone.    In DATA mode this will usually be 1 or 2, but in VOICE mode you
  471. may prefer to select a higher number to give some time to manually
  472. pickup the phone when you are nearby.
  473.  
  474. For VOICE mode, an optional second <number_of_rings> may be specified.
  475. When messages are present in the voice messages recording directory, the
  476. phone is picked up after this second number of rings.
  477. This can be used as a toll saver feature: specify a lower number of rings
  478. in the second number, and when you want to check remotely if messages
  479. are waiting, only let the phone ring as many times as specified here.
  480. You will save the costs of a call when no messages are waiting.
  481. Example:
  482.  
  483. VOICE 4 2
  484.  
  485. Yet another optional item is a capital letter R followed by a (small)
  486. number of rings.  When up to this number of rings are coming in and the
  487. ringing stops before the required number of rings (the earlier numbers
  488. on the same line) has been reached, the program switches to DATA mode
  489. for a fixed amount of time (one minute).
  490. This can be used to place a DATA call to the system while it is in VOICE
  491. mode, using a modem which does not accept the voice reply and without
  492. using DTMF.
  493. First call the number and let it ring once or twice, then wait at least
  494. 15 seconds (at most one minute) and place a second call.  The program
  495. will now answer in DATA mode.
  496. Example:
  497.  
  498. VOICE 4 R1
  499.  
  500. When you are using the "distinctive ring detection" option of the ZyXEL
  501. MODEM, the "state" file should have five lines (or at least one more
  502. than the highest ring type expected from the MODEM).  In this case, the
  503. program will use the n+1'th line of the file when RINGn is received from
  504. the modem.  Example:
  505.  
  506. VOICE 4
  507. VOICE 4
  508. DATA 2
  509.  
  510. MODEM will pickup in VOICE mode after 4 rings when RING or RING1 is
  511. received, and will pickup in DATA mode after 2 rings when RING2 is
  512. received.
  513.  
  514. A small script, /usr/ZyXEL/zstate, is provided to set or display the
  515. contents of the statefile. this is only to be used when distinctive
  516. ringing is not in use, as it only writes a single-line statefile.  when
  517. you have distinctive ringing, you probably never modify the statefile
  518. anyway, and just create it using an editor.
  519.  
  520. The script is used like this:
  521.  
  522.     zstate ttyS1
  523.  
  524. Displays the current content of the statefile for ttyS1, e.g. "VOICE 4".
  525.  
  526.     zstate ttyS1 DATA 2
  527.  
  528. Sets the statefile for ttyS1 to contain "DATA 2".
  529.  
  530.  
  531.  
  532. crontab of user root:
  533.  
  534. In this crontab you can put commands to switch the mode of the program
  535. at specified times of day.  E.g. to run in DATA mode during the night,
  536. and switch to VOICE mode during the day.  Example:
  537.  
  538.     0 23 * * *    /usr/ZyXEL/zstate ttyS1 DATA 2
  539.     30 7 * * *    /usr/ZyXEL/zstate ttyS1 VOICE 4
  540.  
  541. This will put the program in DATA mode for the period 23:00-07:30 each
  542. day (I am using this setup for my BBS)
  543.  
  544.  
  545. Firing it up
  546. ------------
  547.  
  548. After the above changes have been made, and the MODEM has been connected
  549. and switched ON, use "telinit 4" to set the INIT runlevel to 4, which
  550. causes the /sbin/ZyXEL program to be respawned.     (use "telinit q" when the
  551. runlevel already was at 4)
  552. Now, you should see a quick dialogue on the MODEM TXD and RXD LEDs, and
  553. you should hear a short BEEP from the modem to indicate successful
  554. intialization.     After this, the LEDs HS, DTR, CTS and EC should be ON,
  555. the others should be OFF.
  556. When this fails, the is probably a problem with the COM port or the cable
  557. used to connect the MODEM.  Checkout using a terminal program.
  558.  
  559. When you now press the DATA/VOICE button on the MODEM, it will react as
  560. if a call came in.  Depending on the STATE file contents, it will be
  561. in VOICE or in DATA mode.
  562. However, to be operating in VOICE mode you will need pre-recorded messages,
  563. which you first need to record now.
  564.  
  565.  
  566. Recording messages
  567. ------------------
  568.  
  569. To record your own outgoing messages proceed as follows:
  570.  
  571. 1. put the program in VOICE mode (/usr/ZyXEL/zstate ttyS1 VOICE 4)
  572.  
  573. 2. use one of three methods to get connected to the VOICE mailbox:
  574.  
  575. - connect a microphone to the MODEM (see manual), run the "zvmb" program,
  576.   and press V to connect to the VOICE mailbox.    you will use the
  577.   machine's keyboard to enter numbers in this case, and you should not
  578.   type the * and #  (use ENTER instead).  enter 42 to switch the modem to
  579.   use the microphone for input.
  580.  
  581. - or call the MODEM from another phone (e.g. when you have a PBX), and after
  582.   you get a connection and the existing message has been played press '9'.
  583.  
  584. - or connect a microphone to the MODEM (see manual), and press the DATA/VOICE
  585.   button on the MODEM.    Use a 'pocket tone dialer' (DTMF keypad with
  586.   loudspeaker) to generate DTMF tones in this case.
  587.   After the message has been played, press '9'.
  588.   Then type *55#, and the mailbox should answer with a short BEEP.
  589.   This phase may be a little tough as the MODEM was in 'telephone line'
  590.   mode and is not very sensitive.  After the *55# is accepted the
  591.   'microphone' mode has been selected and everything should be fine.
  592.  
  593. 3. enter *51# to record in CELP mode, *52# to record in ADPCM2 mode or
  594.    *53# to record in ADPCM3 mode (these give different quality and data rate)
  595.  
  596. 4. wait for the BEEP, and start recording your message.     The silence detection
  597.    interval is quite short now, so you should continue talking...  You
  598.    can adjust the silence detection interval in the commands file, but
  599.    keep in mind that the period of silence in your recorded message will
  600.    slow down the procedure each time it is played...
  601.    When finished the BEEP-BEEP sound indicates the recording is stopped.
  602.  
  603. 5. enter *41# to replay your message, and repeat the recording if not
  604.    satisfied.
  605.  
  606. 6. now your message is saved in /tmp/record.zad, and you can move that file
  607.    to the proper file in the /usr/ZyXEL/play directory.     the greeting to
  608.    be played when answering in VOICE mode is called "greeting.zad".
  609.  
  610. Repeat this for all the messages you want to record or replace.
  611.  
  612. You can also use .zad files created by any other software that adheres
  613. to the .zad standard file format.  (e.g ZFAX under DOS)
  614.  
  615.  
  616. Remote Control
  617. --------------
  618.  
  619. In general, the MODEM DTMF detection feature seems to be a little
  620. insensitive just after the start of the recording.  Wait a short while
  621. after the BEEP to get better results, or first press *.
  622. (this has gotten a lot better in recent modem firmware versions)
  623.  
  624.  
  625. DTMF functions in VOICE mode are controlled by two files, defined by the
  626. VOICEKEY and VOICECMD entries in the configuration file.
  627. After answering in VOICE mode and playing the greeting message, the
  628. system starts recording an incoming message and is sensitive to
  629. single-key DTMF commands defined in the VOICEKEY file, normally
  630. /usr/ZyXEL/keys.  This file can be modified as desired.      The
  631. distributed version defines the following keys:
  632.  
  633. 1    - instructions for use
  634.  
  635. 2    - replay your own recorded message
  636.  
  637. 3    - record a new message over previous one
  638.  
  639. 4    - erase your own recorded message
  640.  
  641. 5    - call the owner's PAGER (optionally with a numeric message)
  642.  
  643. 6    - goto DATA mode
  644.  
  645. 7    - goto FAX mode
  646.  
  647. 8    - FAXBACK mode, send a FAX selected by a document number
  648.  
  649. 9    - goto command mode
  650.  
  651. 0    - hangup
  652.  
  653. *    - ignored because * has to be pressed on many phones to enable DTMF
  654.  
  655. #    - stop (message, recording), end number
  656.  
  657. The DATA and FAX mode keys switch the program to the indicated mode, and
  658. when a connection cannot be immediately established the program keeps
  659. this mode for two minutes.  Another call coming in during this interval
  660. will be immediately answered in the selected mode, independent of the
  661. mode indicated in the 'state' file.  This allows you to remotely switch
  662. the program to another mode, and then make a call in that mode immediately
  663. afterward.
  664.  
  665. The "command mode" key selects the extended command mode, in which
  666. commands consist of a <*> <digits> <#> sequence.
  667. All codes are numeric entries, for which the decimal value of the digits
  668. between * and # selects the function.  So, *00# is equivalent to *0#.
  669. The * key merely erases all entries made before, effectivily clearing
  670. the number as a startoff.   It can therefore also be used when an entry
  671. error has been made.  (e.g. *52*51# gets processed as '51')
  672.  
  673. Functions in command mode are defined in the VOICECMD file, normally
  674. /usr/ZyXEL/commands.  This file can be modified as desired.   The
  675. distributed version defines the following commands:
  676.  
  677. *0#    - back to VOICE mode (single-key DTMF commands active again)
  678.  
  679. *22#    - switch the answering mode permanently to DATA
  680.  
  681. *23#    - switch the answering mode permanently to FAX
  682.  
  683. *24#    - switch the answering mode permanently to VOICE
  684.  
  685. *33#    - recorded message playback
  686.  
  687. *34#    - archived message playback
  688.  
  689. *41#    - play newly recorded message
  690.  
  691. *42#    - switch to microphone input
  692.  
  693. *43#    - switch to telephone line input
  694.  
  695. *50#    - record new message (CELP)
  696.  
  697. *51#    - record new message (ADPCM2)
  698.  
  699. *52#    - record new message (ADPCM3)
  700.  
  701. *53#    - record new message (ADPCM4)
  702.  
  703. *55#    - record new message (ADPCM2+RESYNC)
  704.  
  705. *56#    - record new message (ADPCM3+RESYNC)
  706.  
  707. *57#    - record new message (ADPCM4+RESYNC)
  708.  
  709. *58#    - record new message (NEW ADPCM3)
  710.  
  711. *59#    - record new message (NEW ADPCM3+RESYNC)
  712.  
  713. *61#    - enter number for callback
  714.  
  715. *62#    - callback selected number
  716.  
  717. others    - see /usr/ZyXEL/commands
  718.  
  719.  
  720. Functions in message playback mode:
  721.  
  722. 0    - leave playback
  723.  
  724. 1    - playback help
  725.  
  726. 2    - tell message date/time
  727.  
  728. 3    - next message
  729.  
  730. 4    - delete message & step to next
  731.  
  732. 5    - archive message & step to next
  733.  
  734. 7    - first message, step forward
  735.  
  736. 8    - play same message again
  737.  
  738. 9    - last message, step backward
  739.  
  740.  
  741. Commands used in /usr/ZyXEL/commands and /usr/ZyXEL/keys files
  742. --------------------------------------------------------------
  743.  
  744. You can program your own actions to be performed when certain DTMF keys
  745. are used, using a set of commands in the "keys" and "commands" files.
  746. For each DTMF key or code, you enter a label in these files (the key
  747. number or code, followed by a colon).  At this label, a number of
  748. commands can be specified, each on a separate line and preceded by a
  749. TAB.  The sequence of commands for a label ends when a new label is
  750. encountered.  There can be empty lines and comment lines in the file for
  751. clarity.  Comment lines start with a #-sign.
  752. In general, commands consist of a keyword and one or more optional
  753. parameters, separated by spaces.  When parameters need to include
  754. spaces (e.g. in the "logmesg" and "say" commands), surround the
  755. parameter by single or double quotes.
  756. The following commands can be used:
  757.  
  758.  
  759. auplay <filename>
  760.     Used to play an audiofile with uLaw data.  When the file starts
  761.     with ".snd" (SUN audio file) it is assumed to contain audio data
  762.     sampled at 8 KHz, starting from byte 32.  Otherwise, it is assumed
  763.     the file has no header and contains audio data sampled at 9.6 KHz.
  764.     The <filename> should be a full pathname.  Note that this command
  765.     is not for playing back ZyXEL audio files.  (see "play" command)
  766.  
  767. beep
  768.     The "beep" command can be used to send audible tones.  Without
  769.     parameter it will sound the tone defined as ERROR in the
  770.     /etc/default/ZyXEL file.  When given a parameter, the specified
  771.     string is sent to the MODEM after a AT+VTX= command.  Check your
  772.     ZyXEL manual for a description of valid strings.
  773.  
  774.     Example: beep [880,0,1][0,0,1][880,0,3][0,0,5]
  775.  
  776. checklevel <num>
  777.     Used in combination with the "userlevel" command to protect
  778.     certain commands from access by unauthorized users.  A
  779.     "checklevel" command will logically-AND the specified level with
  780.     the current "userlevel", and when the result is nonzero it will
  781.     proceed.  When the result is zero, an error is generated and the
  782.     sequence of commands is terminated.  Hence, the commands below
  783.     the "checklevel" are not executed, and are protected from users
  784.     that don't know how to set the userlevel.
  785.     The logical-AND operation means that one can in fact create a
  786.     number of different "user groups", each assigned a power-of-2
  787.     number (1,2,4,8,16 etc).  The "checklevel" command specifies the
  788.     sum of the group numbers that one wants to allow access to the
  789.     commands, and the "userlevel" command specifies the sum of the
  790.     group numbers the user is to be member of.
  791.  
  792.     Example: checklevel 1
  793.  
  794. command
  795.     When issued in /usr/ZyXEL/keys, the voice mailbox goes into
  796.     command (also known as "expert") mode.
  797.  
  798. dialback [<number>]
  799.     Hangs up the line, and dials the number specified in a
  800.     "readnumber" command, or the number specified.
  801.     Voice mode is assumed on the call.  Can be used to reverse
  802.     charges when reading out the voice mailbox, or to test
  803.     reachability of a phone one is testing.     Could also be used to
  804.     dial to some fixed number to indicate a message was entered and
  805.     the caller wants to have it handled immediately (by pressing a
  806.     certain DTMF key)
  807.  
  808. exit
  809.     Exit from the current mode.  Goes back to "key" mode when in
  810.     command mode, hangs up the phone when in "key" mode.
  811.  
  812. fax <filename>|NUMBER [<number>|NUMBER]
  813.     Send a FAX.  The fax to send is either a filename (or directory),
  814.     or the specified document in the FAXPOLL directory (when NUMBER
  815.     is specified, and the "readnumber" command has been used to
  816.     enter the number of the document to be FAXed).
  817.     When <number> is not given or is empty, the FAX is sent on the
  818.     current connection.  Else ZyXEL hangs up the line, and calls the FAX
  819.     specified by <number> or the number keyed in using "readnumber"
  820.     when NUMBER is specified.
  821.     As there is only one NUMBER register, it is not possible to send
  822.     a numbered document to a variable number...
  823.  
  824.     Example: fax /usr/ZyXEL/faxpoll/id0000
  825.  
  826. logmesg <string>
  827.     Logs the specified message to the logfile.
  828.  
  829.     Example: logmesg "Interesting event"
  830.  
  831. mode <mode>
  832.     Switch to a different mode.  <mode> can be:
  833.     DATAFAX - auto-detect DATA or FAX mode
  834.     DATA    - DATA mode only
  835.     FAX    - FAX mode only
  836.  
  837.     The switched mode will be held for two minutes when the
  838.     handshake initially fails, so one can switch the system into
  839.     DATA mode calling from a phone, and then call again using a
  840.     MODEM.
  841.  
  842.     Example: mode DATA
  843.  
  844. pager [<code>|NUMBER]
  845.     Hangs up the line, and calls the PAGER specified by PAGERNUM and
  846.     PAGERTYPE in the /etc/default/ZyXEL file.
  847.     <code>, when specified, will be sent to the paging service as
  848.     information to be displayed on the PAGER.  When NUMBER is
  849.     specified for this argument, the number last read with a
  850.     "readnumber" command is sent as information.
  851.  
  852. play [<filename> [<endstring>]]
  853.     Plays a specified ZyXEL audio datafile to the MODEM.  The file
  854.     should be in the ZyXEL-documented .ZAD format (same as used by
  855.     ZFAX).    The encoding type of the file should be compatible with
  856.     the MODEM used to play it.  (i.e. you can't play CELP files on a
  857.     non-plus modem, or ADPCM4 files on pre-6.13 firmware)
  858.     The optional <endstring> specifies the DTMF keys and events that
  859.     will end the playing before the end-of-file.  Default value of
  860.     this <endstring> is "#bd", i.e. the playing stops when # is
  861.     pressed, or a BUSY or DIALTONE is received.
  862.     When <filename> is not a full pathname (does not start with a
  863.     slash), the file will be located in the PLAYDIR defined in the
  864.     defaults file (usually /usr/ZyXEL/play), and the .zad extension
  865.     is automatically added.     When it is a full pathname, it is not
  866.     further modified.
  867.     When the <filename> is omitted, the current recording file (name
  868.     is dynamically determined at the start of the voice mailbox
  869.     session) is being played.
  870.  
  871.     Example: play greeting
  872.  
  873. playback [<dirname>]
  874.     Message playback mode is entered.  In this mode, files in the
  875.     specified directory are played oldest-first, and DTMF keys can
  876.     be used to step through the files, delete files, or archive
  877.     them.
  878.     When no directory name is specified, the RECDIR directory defined
  879.     in the defaults file is used.  (the directory where incoming
  880.     voice messages are stored)
  881.  
  882. readnumber
  883.     A number (e.g. to be used for dialback) can be keyed in,
  884.     terminated by the # key.  The * key can be used to make
  885.     corrections.  The number is then read aloud, for verification of
  886.     correct entry.
  887.     This command performs no dialing, this is done by the "dialback"
  888.     command and some other commands that use it when the keyword
  889.     NUMBER is used instead of a telephone number or FAX document number.
  890.  
  891. record [<filename> [<endstring> [<vsd-string> [<vsm-value> [<maxtime>]]]]]
  892.     Record audio into a diskfile.
  893.     When no filename is specified, the current recording file (name
  894.     is dynamically determined at the start of the voice mailbox
  895.     session) is used.
  896.     The optional <endstring> determines the events that end the
  897.     recording.  Default is "#bdq" (DTMF # key, BUSY tone, DIALTONE
  898.     or quiet line for the specified silence interval).
  899.     The <vsd-string> determines the silence detection parameters.
  900.     When it is omitted or empty, the SILENCE value specified in the
  901.     /etc/defaults/ZyXEL file is used.
  902.     The <vsm-value> determines the recording mode used.  When it is
  903.     omitted or empty, the RECMODE value from the defaults file is
  904.     used.
  905.     Finally, the maximum time of the recording can be specified,
  906.     the default is 120 seconds.
  907.  
  908.     Example: record /tmp/record.zad #bdq 20,10 0 60
  909.  
  910. recLS <LS-nr>
  911.     Sets the input device to be used for recording.
  912.     valid values are:
  913.     0    - use the device being used for playback
  914.     2    - use the telephone line
  915.     8    - use an external microphone plugged into the LINE
  916.           connector
  917.  
  918. remove [<filename>]
  919.     Removes the specified file.  When no filename is specified, the
  920.     current recording file (name is dynamically determined at the
  921.     start of the voice mailbox session) is removed.
  922.     BE CAREFUL: the program runs as "root", hence any file on the
  923.     system can be removed using this command.
  924.     As only "root" can edit the command files and can issue this
  925.     command in immediate mode, there should be no security
  926.     consequences.  This would change when the /etc/default/ZyXEL
  927.     file and/or the commands and keys files are publicly writable!
  928.  
  929. run [<envvar>=<value>...] <command> [<args>...]
  930.     Run an external program.  Any parameters of the form VAR=value
  931.     will be put in the environment, the remainder of the line is
  932.     the program name (must be full pathname) and the arguments for
  933.     the command.
  934.     The program will be run with STDIN and STDERR attached to
  935.     /dev/null, and STDOUT attached to the speech synthesizer (when
  936.     enabled).  For correct operation, the program should perform its
  937.     action, write a short text on STDOUT, and then exit.  The speech
  938.     generated from the output text should be less than 2 minutes in
  939.     length, and the program itself should require less than 1 minute
  940.     runtime.  Normally, the program will just be some small status
  941.     report or change.
  942.     The following strings in <args> are treated special:
  943.     @C    - will be replaced by the last CONNECT received from modem
  944.     @L    - will be replaced by the name of the tty (e.g. "ttyS1")
  945.     @N    - will be replaced by the last string read using "readnumber"
  946.     @R    - will be replaced by the name of the current recording file
  947.     @S    - will be replaced by the system name
  948.  
  949.     Example: run /usr/bin/fortune
  950.  
  951.     BE CAREFUL with this command!  The program is run with "root"
  952.     privileges.
  953.  
  954. say <string>
  955.     Call the text-to-speech synthesizer to say the specified English
  956.     text.  This is best used only for short directives (e.g. mode
  957.     changes, prompts) as the quality of the speech is sub-optimal.
  958.  
  959.     Example: say "expert mode"
  960.  
  961. userlevel <level>
  962.     Set the current userlevel to the specified numeric value.
  963.     This is used with "checklevel" to protect certain commands
  964.     from unauthorized access.
  965.     The protection is achieved by hiding this command under a
  966.     longish command number, so that it is unpractical for a caller
  967.     to try all possible commands until it is found.
  968.  
  969.     Example: userlevel 1
  970.  
  971.  
  972. The speech synthesizer
  973. ----------------------
  974.  
  975. The speech synthesizer included with the package is the "rsynth-2.0"
  976. program by Nick Ing-Simmons.  Only small patches were made to interface
  977. it with ZyXEL.
  978. For full documentation of the synthesizer, get the package from
  979. svr-ftp.eng.cam.ac.uk (filename comp.speech/sources/rsynth-2.0.tar.gz).
  980.  
  981. The synthesizer can use an optional dictionary.     The "mkdictdb" program
  982. is provided to load the dictionary database from a textfile containing
  983. english words and their pronounciation.     Such a file can be found on:
  984. ftp.cs.cmu.edu (filename project/fgdata/dict/cmudict.0.3.Z).
  985. Uncompress it, and load it into the database using:
  986.     mkdictdb cmudict.0.3 aDict.db
  987.     mkdir /usr/lib/dict
  988.     mv aDict.db /usr/lib/dict
  989.  
  990. Some warnings about invalid words will be issued.  These can be ignored.
  991. Note that the database takes about 9 MB of diskspace...
  992. Alternatively, a British (vs. American) version of the dictionary can
  993. be found on the rsynth-2.0 site.  See the rsynth README for more details.
  994.  
  995. With the dictionary the speech quality is much better than without, but
  996. it still is very difficult to understand phrases which are dynamically
  997. generated and you cannot predict beforehand.  The best use of the speech
  998. synthesizer is for confirmation strings and short prompts.  It saves the
  999. effort of having to record numerous short strings in files to be played
  1000. using the "play" command.
  1001.  
  1002.  
  1003. Using "zvmb"
  1004. ------------
  1005.  
  1006. "zvmb" is a very simple program, which was mainly developed to test
  1007. the API FIFO interface of the program.    A more friendly program has
  1008. to be developed for user interaction.
  1009. However, zvmb is now usable to do some interaction with the VOICE
  1010. mailbox, and it is more comfortable that the earlier method, which
  1011. worked by connecting a microphone and using a DTMF keypad to issue
  1012. commands...
  1013.  
  1014. When "zvmb" has been started, it tells you how to quit from it:
  1015.  
  1016. ZyXEL VoiceMailBox user interface - Hit RETURN for MENU
  1017. Use ^C to quit
  1018.  
  1019. Please remember this :-)  (it is the INTR key defined for your terminal,
  1020. when ^? appears, the DEL key is meant)
  1021. You can press ENTER to get a menu of available commands:
  1022.  
  1023. ZyXEL 1.5 (Feb    4 1995 02:03:42)   (c) 1993,1994 by Rob Janssen, PE1CHL
  1024.  
  1025. Commands are:
  1026. !          Print ZyXEL pid
  1027. #          Print program version
  1028. $          Print MODEM version
  1029. >          Set output fifo/file/tty
  1030. S          Use SPEAKER for playback (default)
  1031. L          Use LINE for playback
  1032. V          Access VoiceMailBox
  1033. C<command>      Execute VoiceMailBox command
  1034. P<file>          Playback
  1035. R<n>          Record over line <n>
  1036. F<number> <file>  Send a FAX
  1037. Q<number> <id>      Poll for FAX
  1038. D          Hold DATA/FAX mode for 5 minutes
  1039. AT<cmd>          Issue MODEM command
  1040.  
  1041.  
  1042. Typing one of these commands followed by <return> or <space> will
  1043. perform the indicated action.
  1044. The commands !, #, $ and > are intended for use by "pretty" user
  1045. interfaces, e.g. using Tcl/Tk.    An example of such an interface is now
  1046. included, but it needs some more work.    Don't hesitate to volunteer :-)
  1047.  
  1048. S and L are used to set the output device for VOICE mailbox message
  1049. playback.  Messages can be played back through the MODEM internal
  1050. speaker, or to a speaker or telephone handset connected to the LINE
  1051. terminal of the MODEM (see MODEM manual, end of chapter 14).
  1052. The internal speaker is attractive because it requires no plugging or
  1053. switching of the line, but the quality of playback is awful.  Use the
  1054. LINE option for HI-FI playback :-)  (but you need to connect a handset)
  1055.  
  1056. V is used to access the VOICE mailbox.    You will be dropped into the
  1057. mailbox at the point where you normally are after listening to the
  1058. announcement message, and pressing 9 to enter command mode.
  1059. Your userlevel will have been set according to the APIUSERLEVEL=
  1060. line in the /etc/default/ZyXEL file, so that you will not have to
  1061. enter the password code in personal-use environments. (APIUSERLEVEL=7)
  1062. Now, you can enter any code defined in the /usr/ZyXEL/commands file,
  1063. and enter 0 to exit from the VOICE mailbox.
  1064. When the default commands file is in place, 33 will enter the message
  1065. playback mode, where you can handle messages that have arrived.
  1066.  
  1067. F is used to send a FAX.  First, you need to prepare the outgoing FAX,
  1068. depending on the type of FAX support that was compiled in the program.
  1069. (See the FAX subheading for more details)
  1070. Then send the FAX by typing: F number faxfile [ENTER], e.g.:
  1071. F 030715610 /tmp/faxfile
  1072. The faxfile pathname must be a full pathname, as it is interpreted by
  1073. the running ZyXEL program which does not have the same working directory
  1074. as "zvmb" has.
  1075. The result of sending the FAX is reported, you will have to re-try when
  1076. it fails.
  1077.  
  1078. Q is used to poll for an incoming FAX.    Type Q number id <ENTER> to call
  1079. the specified number and ask for a FAX.     When it is available, it will
  1080. be received and stored in the incoming FAX directory.
  1081. the "id" is a 4-digit number which will be sent to the remote FAX as a
  1082. poll id.  Use 0000 when you don't know which ids it handles, often the
  1083. id will not even be used.
  1084. Example: Q 030715610 0000
  1085.  
  1086. The D command can be used to enable DATA mode calling for a brief time.
  1087. E.g. someone wants to access your BBS or UUCP dialin, and has called
  1088. you about this.     Now, you can start "zvmb", issue the D command and
  1089. leave "zvmb" again.  The modem will answer in DATA mode when a call
  1090. comes in within 5 minutes.
  1091.  
  1092. Any line starting with A will be sent to the modem, allowing some AT
  1093. commands to be issued to print the modem status.
  1094. ATI2 will print the ZyXEL LINK STATUS REPORT, reporting the statistics
  1095. for the last DATA-mode CONNECT.     Just for the curious... :-)
  1096. Note that an AT command that will set some mode of the modem will be
  1097. cancelled as soon as "zvmb" is terminated, as the modem is re-initialized
  1098. at that time...
  1099.  
  1100.  
  1101. FAX
  1102. ---
  1103.  
  1104. Up to the 1.4 version of the program exclusively uses the ZFAX mode of
  1105. sending and receiving FAXes.  Support for CLASS 2 mode is in version 1.5.
  1106. The FAX mode can be selected when compiling the program from source, see
  1107. the README file in the source kit.  CLASS 2 is selected in the binary
  1108. distribution, as it provides more features (most notably, while sending
  1109. FAXes).     However, ZFAX mode can be used when you want to conveniently
  1110. handle FAXes on machines with little memory.
  1111.  
  1112. When the program has been compiled to support ZFAX:
  1113. To prepare FAXes for sending, and to decode the received FAX files,
  1114. one needs to use the ZFAX program which is distributed by ZyXEL with
  1115. the modem (and updated versions are available from ftp.zyxel.com).
  1116. This program unfortunately runs under DOS, but it works well under the
  1117. newer releases of "dosemu".  When you have configured "dosemu" to do
  1118. direct access to the video card you can view FAXes directly.  If not,
  1119. you can still convert them to printer files or PCX files, and process
  1120. these with other tools.
  1121.  
  1122. When the program has been compiled to support CLASS 2 FAX:
  1123. The FAXes to be sent can be in various different formats.  A FAX can be
  1124. a single file, or it can be a directory containing a mix of files of
  1125. different types.  When you put the files in a directory, use a naming
  1126. convention so that the pages will go out in sequence when the files are
  1127. sorted alphabetically.    (e.g.  name the files p01.g3, p02.g3 etc)
  1128.  
  1129. A file to be FAXed can be of the following types:
  1130.  
  1131. 1. plain G3 file, without header information.
  1132.  
  1133.    As ZyXEL cannot determine the resolution and coding from the file,
  1134.    use the following naming convention to help it:
  1135.  
  1136.    Normal resolution, 1-d coding:  filename_n1.g3
  1137.    Normal resolution, 2-d coding:  filename_n2.g3
  1138.    Fine resolution,   1-d coding:  filename_f1.g3
  1139.    Fine resolution,   2-d coding:  filename_f2.g3
  1140.                        ^^^^^^
  1141.  
  1142. 2. Digifax file, as produced by Ghostscript, with one or more pages in
  1143.    the file.
  1144.  
  1145.    These formats are preferred when the system is slow, as they can be
  1146.    sent to the MODEM without any conversion.  Conversion while sending
  1147.    is timing-critical, as there are quite short timeouts in the FAX
  1148.    protocol.  When using Ghostscript, a single outputfile can be used
  1149.    containing all the pages (some other FAX packages need a separate
  1150.    file for each page).     Use this command to prepare a file using
  1151.    Ghostscript:
  1152.  
  1153.      gs -sDEVICE=dfaxhigh -sOutputFile=faxfile.g3 -q -dNOPAUSE - <input.ps
  1154.  
  1155.    Instead of "dfaxhigh", "dfaxlow" can also be used (normal resolution
  1156.    mode).
  1157.    Note that the resolution should match the resolution negotiated
  1158.    during connect with the remote FAX.    When you use high resolution and
  1159.    the remote FAX does not support it, the transfer will fail.
  1160.  
  1161. 3. Postscript file.
  1162. 4. gzip'ed Postscript file.
  1163.  
  1164.    These formats are converted to FAX files by running "gs" with options
  1165.    similar to those shown above as a process forked by ZyXEL.  The
  1166.    advantage of this method is that the resolution (normal/fine) can be
  1167.    dynamically determined at the moment the connection is made, and
  1168.    therefore the formatting is always correct.
  1169.    However, formatting a Postscript page can take quite some time, and
  1170.    this may cause timeouts.  There is usually no problem with simple
  1171.    text documents, but there may be trouble when there are complicated
  1172.    drawings, especially on the first page.
  1173.    (on subsequent pages, Gostscript has had time to work during the time
  1174.    it takes to transfer the first page)
  1175.  
  1176. 5. Shell script
  1177.    When a file starts with #! and is executable, it will be executed and
  1178.    the output it produces on stdout will be formatted by Ghostscript.
  1179.    This provides the mechanism to send dynamically generated FAXes, mainly
  1180.    useful for polling and faxback.
  1181.    To send normal text, convert it to Postscript inside the script, e.g.
  1182.    using "pstext" or "nenscript".  It is also possible to include a
  1183.    short Postscript program at the beginning of the output that does the
  1184.    conversion.
  1185.  
  1186. 6. Plain text
  1187.    Files that look like plain text (not one of the above types, and the
  1188.    first 4 bytes are in the range 01-7F) are converted to Postscript by
  1189.    executing the "pstext" program, and then fed to Ghostscript for
  1190.    conversion to FAX format.
  1191.  
  1192. The file types are not determined by the filename (except for the normal/
  1193. fine and 1-d/2-d selection for raw G3 data), but by content of the first
  1194. bytes of the file.  Hence, it is possible to use files without extension.
  1195.  
  1196.  
  1197. Recevied FAXes are stored as a series of files in a directory, and can
  1198. be viewed by processing the data with g3topbm, e.g.:
  1199.  
  1200.     g3topbm <file | xv -
  1201.  
  1202.  
  1203.  
  1204. Calling out
  1205. -----------
  1206.  
  1207. To use the modem to place an outgoing call, you will have to use the
  1208. /dev/ttySx device, i.e. the same device as the ZyXEL program is also
  1209. using to access the modem.  You may have been using /dev/cuax until now,
  1210. to let the system arbitrate between incoming and outgoing calls on the
  1211. modemline.  However, this arbitration is based on the availability of
  1212. the DCD signal to indicate an incoming call, and the ZyXEL modem does
  1213. not provide this signal in VOICE mode.
  1214. Therefore, the program has to operate the serial port in a different
  1215. mode than getty does, and you cannot make use of the /dev/cuax device.
  1216. Other programs that allow the use of the ZyXEL modem with Linux have the
  1217. same characteristic.
  1218.  
  1219. To prevent problems when another program opens the serial port while the
  1220. ZyXEL program is busy chatting with the modem, or vice-versa, a lock
  1221. file has to be created in a pre-defined place.    The presence of this
  1222. file indicates that the line is in use.
  1223. This lockfile is correctly created by programs like uucico, cu, seyon.
  1224. Your favorite terminal program may need to be configured to create (and
  1225. check) the lockfile.  Check this out when you notice that the ZyXEL
  1226. program interferes with your use of the modem.
  1227.  
  1228. The directory, name and contents of the lockfile can be configured
  1229. while compiling the program.  On a Linux system, these files usually
  1230. live in /usr/spool/uucp, and are named LCK..ttySx (to match the name
  1231. of the line the modem is on).  The contents of the file are the PID
  1232. of the program that is actively using the MODEM at that time, as an
  1233. ASCII string.  Alternatively, the PID may be written in the file in
  1234. binary (4 bytes).
  1235. On UNIX system 5 release 4, the lock files are in /usr/spool/locks,
  1236. are named LK.dev.major.minor (to match the device, major and minor
  1237. numbers of the tty node), and the contents are also the ASCII PID.
  1238. This behaviour can be selected at compile time using the symbol
  1239. SVR4LOCKS in the source.
  1240.  
  1241. To get the correct modem settings when calling out, store them in the
  1242. modem's profile 0.  The ZyXEL program sets AT&D3 during initialization,
  1243. so whenever a program wants to call out, it can just make DTR low for a
  1244. moment to cause a modem reset and restore of settings from profile 0.
  1245. Just calling out without a modem reset will not work, because the ZyXEL
  1246. program keeps the modem in VOICE mode while waiting for rings.    When the
  1247. program you use to call out cannot lower DTR during initialization, you
  1248. should send the ATZ command to reset the modem before sending the dial
  1249. command.
  1250.  
  1251. Suitable settings for storage in profile 0 could be:
  1252.  
  1253.     AT&F        <- reset to factory defaults
  1254.     ATS42.6=1    <- no RINGING response (confuses some programs)
  1255.     ATS48.2=1    <- send DATA CNG tone when calling out
  1256.     ATP        <- only when pulse-dialling required
  1257.     AT&W0        <- write this in profile 0
  1258.  
  1259. Add other settings as you prefer.  Don't issue this sequence as part of
  1260. the initialization procedure of your program, as you will wear out the
  1261. EEPROM used for saving profiles.  The AT&W0 command should be used only
  1262. manually.
  1263.